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Foreword 



This Technical Specification has been produced by the 3^ Generation Partnership Project (3 GPP). 

3GPP acknowledges the contribution of the Parlay X Web Services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3 GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3 GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 9 of a multi-part deliverable covering the 3^ Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OS A); Parlay X Web Services, as identified 
below: 
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1 Scope 

The present document is Part 9 of the Stage 3 Parlay X Web Services specification for Open Service Access (OSA). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Terminal Location Web Service aspects of the interface. All aspects of the Terminal 
Location Web Service are defined here, these being: 

Name spaces. 

Sequence diagrams. 

Data definitions. 

Interface specification plus detailed method descriptions. 

Fault definitions. 

Service policies. 

WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CN WG5, ETSI TISPAN and The Parlay Group. 
Maintenance of up to 3GPP Rel-8 and new OSA Stage 1, 2 and 3 work beyond Rel-9 was moved to OMA in June 2008. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22.127: "Service Requirement for the Open Services Access (OSA); Stage 1". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X web services; Part 1: Common". 

[7] ISO 6709: "Standard representation of latitude, longitude and altitude for geographic point 

locations". 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] apply. 

4 Detailed service description 

Terminal Location provides access to the location of a terminal through: 

• Request for the location of a terminal. 

• Request for the location of a group of terminals. 

• Notification of a change in the location of a terminal. 

• Notification of terminal location on a periodic basis. 

• Location is expressed through a latitude, longitude, altitude and accuracy. 

When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the 
service to provide results based on a number of criteria including number of terminals for which the request is made and 
amount of time required to retrieve the information. This allows the requester to initiate additional requests for those 
terminals for which information was not provided. 

5 Nannespaces 

The Terminal Location interface uses the namespace: 

http ://w w w. c sapi . org/wsdl/parlayx/terminal_location/v4_0 
The TerminalLocationNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_location/notification_manager/v4_0 
The TerminalLocationNotification interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/terminal_location/notification/v4_0 
The data types are defined in the namespace: 

http ://w w w. c sapi . org/schema/parlayx/terminal_location/v4_0 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in 
XML Schema [5]. The use of the name 'xsd' is not semantically significant. 
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6 Sequence diagrams 

6.1 Terminal location query 

Pattern: Request / Response. 

For an application to determine the location of a terminal device, it provides a terminal device address and desired 
accuracy, and receives the location for the device requested. 



: Application 



: Terminal Location 
Web Service 



Request terminal location 

^ 



T 



U 



Retrieve location 
" < ' 



Location data 



Figure 1 
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6.2 Terminal location group query 



Pattern: Request / Response. 

When an application requires the locations of a set of terminal devices, it may provide an array of terminal device 
addresses, including network managed group addresses, and receive the location data for the set of devices requested. 



: Terminal Location 
Web Service 



Application 



Request terminal location for group 
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Location data 
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Figure 2 
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6.3 Terminal location notification 

Pattern: Application Correlated Multiple Notification. 

An application can be notified of a terminal device entering or leaving a geographical area. When a matching event 
occurs; a notification message will be sent to the application. 



: Application 



: Terminal Location 
Web Service 



: Notification 
Application 



: Notification 
Web Service 



Create correlation id 



^ 
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Create notification with correlator 

^ 



At some later time, an event occurs to 
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otification with correlate!' 



At some later time, the notification may 
be cancelled 



Canc^el notification with corrdator 



Figure 3 



ETSI 



3GPP TS 29.199-09 version 9.0.0 Release 9 



11 



ETSI TS 129 199-9 V9.0.0 (2010-01) 



6.4 



Terminal location notification with check immediate 



In some applications, the terminal location notification will be used to watch for a specific location change. An example 
is a 'call when present' service, where the terminal location is checked and determined to be outside the target area, and 
a notification is set up to notify the application when the terminal enters the target area. Between the time of the original 
location determination and the time the notification is set up, the terminal could move into the target area - thus the 
notification on entry into the target area would not be sent. 

Using the check immediate flag, after the notification is established, the terminal location will be determined, and if the 
terminal is in the target area, then a notification will be sent immediately. The following sequence diagram shows this 
scenario. 



: Application 



: Terminal Location 



Web Service 



: Terminal Location 
Notification 



: Notification 
Application 



: Notification 
Web Service 



Get location 



Location 



Create correlator 



^^ 



T Start geographical notification with check immediate 



Set up notification 

< ^ 

Check terminal location 



<r^ 



Location notification 



Apply count to notification 

\< ' 



Status end 



Void 



^^- 



Figure 4 
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This sequence shows: 

• The Enterprise Application checks the location of a terminal, and receives its location (in this scenario 
determining that the terminal is outside the target area). 

• The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the 
Enterprise Web Service when the terminal enters the target area and the check immediate flag set to true. 

• Sets up the notification to monitor terminal location. 

• Check the current location of the terminal, and determine if the terminal lies inside the target area. 

• In this case, the terminal is in the target area, and a notification is delivered to the Enterprise Web Service. 

• The count of notifications is incremented and compared to the notification count limit. 

• In this case, a single notification was requested, and the end notification message is sent. 

• The startGeographicalNotification operation completes. 

This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be 
received concurrent with the creation of the notification. 

6.5 Terminal location periodic notification 

Pattern: Application Correlated Multiple Notification. 

An application can be notified of a terminal device location on a periodic basis. At each interval, a notification message 
will be sent to the application. 
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Figure 5 
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6.6 



Distance notification 



An application may request to monitor locations for two or more terminal devices and be notified either when those 
devices get within or beyond a specified distance, depending on selected criteria for triggering notifications. The 
application can be notified in the events such as: 

• when all monitored devices get within the specified distance or, 

• when any of the monitored devices gets within the specified distance or, 

• when all monitored devices are beyond the specified distance or, 

• when any of the monitored devices gets beyond the specified distance 



Application 



: Terminal Location 



Web Service 



: Notification 
Application 



: Notification 
Web Service 



Creaie correlation id 



: 



^ 



Create notification with correlator 
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T 



At some later time, an event occurs to 
trigger the notification 



N 



At some later time, the notification may ^ 
be cancelled 



fklotification with correiatoi- 



Canc^el notification with correlator 

>r 



Figure 6 



6.7 



Distance notification witii ciieck immediate 



For some applications, the distance notification could be used to watch for a specific event; for example when two 
terminal devices get close to each other within a specified distance. Using the check immediate flag, after the 
notification is established, the terminal locations will be determined, and if both terminals are within a specified 
distance, then a notification will be sent immediately if the criteria is AUWithinDistance. The following sequence 
diagram shows such scenario. 
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: Application 
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Figure 7 



7 XML Schema data type definition 

7.1 Latitude and Longitude values 

Latitude and longitude values used in the present document follow the conventions of the ISO 6709 [7] specification, as 
it applies to latitudes and longitudes specified using decimal degrees. 

Latitude values are expressed as floating point numbers in the range -90.0000 to +90.0000, using decimal degrees (as 
opposed to minutes and seconds). Positive values indicate locations north of and on the equator. Negative values 
indicate locations south of the equator. 

Longitude values are expressed as floating point numbers in the range -180.0000 to +180.0000, using decimal degrees 
(as opposed to minutes and seconds). Positive values indicate locations east of and on the prime meridian (Greenwich). 
Negative values indicate locations west of the prime meridian up to the 1 80* meridian. 



ETSI 



3GPP TS 29.199-09 version 9.0.0 Release 9 



15 



ETSI TS 129 199-9 V9.0.0 (2010-01) 



7.2 Accuracy values 



Two accuracy values are used in some of the operations. These values express the desire of the application for the 
location information to be provided by the Web Service. The choice of values may influence the price that the Service 
Provider charges. 

The 'requested accuracy' expresses the range in which the application wishes to receive location information. This may 
influence the choice of location technology to use (for instance, cell sector location may be suitable for requests 
specifying 1 000 meters, but GPS technology may be required for requests below 100 meters). 

The 'acceptable accuracy' expresses the range that the application considers useful - if the location cannot be determined 
within this range, then the application would prefer not to receive the information. For instance, a taxi tracking service 
to determine the closest taxi to a person may not be useful if the accuracy cannot be provided within 1 000 meters to 
provide prompt service. This will also reduce customer satisfaction issues, since results that are not useful can be 
handled appropriately for billing (e.g. Service Provider may choose not to bill for these). 

In triggered notifications, a tracking accuracy is defined. This accuracy refers not to the accuracy for the area being 
checked against, but rather for the accuracy of the technology used to track the terminal. For instance, a fine grained 
tracking accuracy would be suitable for tracking the terminal entering a specific location, like a person arriving at a 
destination building. A coarse grained tracking accuracy would be appropriate for determining when a person has 
arrived at a city after a plane trip or a truck nearing the vicinity of a warehouse. 

The "maximum_age" expresses the maximum age that the application considers useful. This can be used by the service 
provider to supply cached location information rather than always do a direct network location request. 

The "response time" expresses the expected response time from an application point of view. If the network is unable to 
respond within the desired time frame the application would prefer not to have the information as it may no longer be 
useful. 

The "tolerance" expresses the priority of response time versus accuracy. If the application is delay tolerant the network 
is expected to return a location with the requested accuracy even if this means not complying with the requested 
response time. The application can also indicate that it is more important that the location information is returned within 
the requested time even if this implies that the requested accuracy can not be fulfilled. An indication of "no delay" 
which implies that the application expects the service provider to return any current location estimate immediately. 

7.3 EnteringLeavingCriteria enumeration 

Indicator for whether the notification is related to entering an area or leaving an area. 



Enumeration 


Description j 


Entering 


Terminal is entering an area 


Leaving 


Terminal is leaving an area 



7.4 



Location Info structure 



Location information represented as a coordinate. 



Name 


Type 


Optional 


Description 


Latitude 


xsd:float 


No 


Location latitude 


Longitude 


xsd:float 


No 


Location longitude 


Altitude 


xsd:float 


Yes 


Location altitude 


Accuracy 


xsd:int 


No 


Accuracy of location provided in meters 


Timestamp 


xsd:dateTime 


No 


Date and time that location was collected 
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7.5 



Void 



7.6 



LocationData structure 



Data structure containing device address, retrieval status and location information. As this can be related to a query of a 
group of terminal devices, the ReportStatus element is used to indicate whether the information for the device was 
retrieved or not, or if an error occurred. 



Name 


Type 


Optional 


Description 


Address 


xsd:anyURI 


No 


Address of the terminal device to which the location information 
applies 


ReportStatus 


common:RetrievalSta 
tus 


No 


Status of retrieval for this terminal device address 


CurrentLocation 


Locationlnfo 


Yes 


Location of terminal. It is only provided if 
ReportStatus=Retrieved. 


Errorlnformation 


common:ServiceError 


Yes 


If ReportStatus=Error, this is the reason for the error. Error due 
to privacy verification will be expressed as POL0002 in the 
ServiceError. 



7.7 



DelayTolerance enumeration 



Enumeration of the delay tolerance items that forms part of the location request. 



Enumeration 


Description 


NoDelay 


The server should immediately return any location estimate that it currently has. If no estimate is 
available, the server shall return the failure indication and may optionally initiate procedures to 
obtain a location estimate (e.g. to be available for a later request). 


LowDelay 


Fulfilment of the response time requirement takes precedence over fulfilment of the accuracy 
requirement. The server shall return any current location estimate with minimum delay. The 
server shall attempt to fulfil any accuracy requirement, but in doing so shall not add any 
additional delay (i.e. a quick response with lower accuracy is more desirable than waiting for a 
more accurate response). 


DelayTolerant 


Fulfilment of the accuracy requirement takes precedence over fulfilment of the response time 
requirement. If necessary, the server should delay providing a response until the accuracy 
requirement of the requesting application is met. The server shall obtain a current location with 
regard to fulfilling the accuracy requirement. 



7.8 DistanceCriteria enumeration 

Indicates what events can trigger distance notification. 



Enumeration 


Description 


AIIWithinDistance 


All monitored devices are within the specified 
distance 


AnyWithinDistance 


Any of monitored devices gets within the specified 
distance 


AIIBeyondDistance 


All monitored devices are beyond the specified 
distance 


AnyBeyondDistance 


Any of monitored devices gets beyond the 
specified distance 



8 



Web service interface definition 



8.1 



Interface: TerminalLocation 



Request the location for a terminal. 
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8.1 .1 Operation: GetLocation 



This operation is intended to retrieve the location for a single terminal. The accuracy requested is the desired accuracy 
for the response. The acceptable accuracy is the limit acceptable to the requester. If the accuracy requested cannot be 
supported, a PolicyException (POL0230) will be returned to the application. If the accuracy of the location is not within 
the acceptable accuracy limit, then the location will not be returned, instead a ServiceException (S VC0200) will be 
returned. The URI provided is for a single terminal, not a group URL If a group URI is provided, a PolicyException will 
be returned to the application. If the requester is not authorized to retrieve location info, a PolicyException(POL0002) 
will be returned. 

If tolerance is indicated this affects the priority of accuracy, response time and maximum estimate age. 



8.1.1.1 



Input message: GetLocationRequest 



Part name 


Part type 


Optional 


Description 


Requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting the information. 
The application invokes this operation on behalf of this entity. 
However, it should NOT be assumed that the application has 
authenticated the requester. If this part is not present, the 
requesting entity is the application itself. 


Address 


xsd:anyURI 


No 


Address of the terminal device for which the location information is 
requested 


RequestedAccuracy 


xsd:int 


No 


Accuracy of location information requested 


AcceptableAccuracy 


xsd:int 


No 


Accuracy that is acceptable for a response 


Maximum Age 


common:TimeMetric 


Yes 


Maximum acceptable age, in seconds, of the location information 
that is returned 


ResponseTime 


common:TimeMetric 


Yes 


Indicates the maximum time that the application can accept to wait 
for a response 


Tolerance 


DelayTolerance 


No 


Indicates the priority of response time versus accuracy 



8.1.1.2 



Output message: GetLocation Response 



Part name 


Part type 


Optional 


Description 


Result 


Locationlnfo 


No 


Location of the terminal for which location information was requested 



8.1.1.3 



Referenced faults 



ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid address(es) - if the requested terminal device address does not exist. 

• SVC0200: Accuracy out of limit. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0002: Privacy error. 

• POL0006: Groups not allowed. 

• POL0230: Requested accuracy not supported. 

8.1 .2 Operation: GetTerminalDistance 

This operation is intended to determine the distance of a terminal from a location. The URI provided is for a single 
terminal, not a group URI. If a group URI is provided, a PolicyException will be returned to the application. 
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8.1.2.1 



Input message: GetTernninalDistanceRequest 



Part name 


Part type 


Optional 


Description 


Requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting the information. The application 
invokes this operation on behalf of this entity. However, it should NOT be 
assumed that the application has authenticated the requester. If this part is 
not present, the requesting entity is the application itself. 


Address 


xsd:anyURI 


No 


Address of terminal to check 


Latitude 


xsd:float 


No 


Latitude of the location to measure from 


Longitude 


xsd:float 


No 


Longitude of the location to measure from 



8.1.2.2 



Output message: GetTerminalDistanceResponse 



L Part name 


Part type 


Optional 


Description 


Result 


xsd:int 


No 


Distance from terminal to the location specified in meters 



8.1.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid address(es) - if the requested terminal device address does not exist. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0002: Privacy error. 

• POL0006: Groups not allowed. 
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8.1 .3 Operation: GetLocationForGroup 



The getLocationForGroup operation initiates a retrieval activity, where one or more terminals, or groups of terminals, 
may have their locations determined. The accuracy requested is the desired accuracy for the response. If the accuracy 
requested is not supported, a PolicyException (POL0230) will be returned to the application. If the location retrieved is 
not within the acceptable accuracy limit, then the location data will contain a ServiceError (SVC0200). 

If tolerance is indicated this affects the priority of accuracy, response time and maximum estimate age. 

The Web Service may return a result set that does not include complete information, allowing the Web Service 
implementation to choose to deliver a partial set of results to accommodate other conditions, such as avoiding timeouts. 
In this case, the addresses for which no attempt was made to provide data will be marked NotRetrieved in the result for 
each address for which a location retrieved was not attempted. 



8.1.3.1 



Input message: GetLocationForGroupRequest 



Part name 


Part type 


Optional 


Description 


Requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting the information. The 
application invokes this operation on behalf of this entity. 
However, it should NOT be assumed that the application 
has authenticated the requester. If this part is not present, 
the requesting entity is the application itself. 


Addresses 


xsd:anyURI 
[1.. unbounded] 


No 


List of URIs to get location for, including group URIs 


RequestedAccuracy 


xsd:int 


No 


Accuracy of location requested in meters 


AcceptableAccuracy 


xsd:int 


No 


Accuracy that is acceptable for a response in meters 


Maximum Age 


common:TimeMetric 


Yes 


Maximum acceptable age, in seconds, of the location 
information that is returned 


ResponseTime 


common:TimeMetric 


Yes 


Indicates the maximum time that the application can accept 
to wait for a response 


Tolerance 


DelayTolerance 


No 


Indicates the priority of response time versus accuracy 



8.1.3.2 



Output message: GetLocationForGroupResponse 



Part name 


Part type 


Optional 


Description 


Result 


LocationData [1 ..unbounded] 


No 


Set of results for the request 



8.1.3.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid addresses. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOO 1 : Policy error. 

• POL0002: Privacy error. 

• POL0003: Too many addresses. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

• POL0013: Addresses duplication 

• POL0230: Requested accuracy not supported. 
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8.2 Interface: TerminalLocationNotificationManager 

Set up notifications for terminal location events using geographical based definitions. 

8.2.1 Operation: StartGeographicalNotification 

Notifications of location changes are made available to applications. The number and duration of notifications may be 
requested as part of the setup of the notification or may be governed by service policies, or a combination of the two. 

If Checklmmediate is set to true, then the notification will be set up, and then the current value of the terminal location 
will be checked. If the terminal location is within the radius provided and the criteria is Entering or is outside the radius 
and the criteria is Leaving, a notification will be sent to the application. This notification will count against the count 
requested. This addresses the case where the location of the device changes during the time the notification is being set 
up, which may be appropriate in some applications. 

The correlator provided in the reference must be unique for this Web Service at the time the notification is initiated, 
otherwise a ServiceException (SVC0005) will be returned to the application. 

If the frequency requested is more often than allowed by the service policy, then the value in the service policy will be 
used. If the duration requested exceeds the time allowed in the service policy, then the value in the service policy will 
be used. If the notification period (duration) ends before all of the notifications (count) have been delivered, then the 
notification terminates. In all cases, when the notifications have run their course (by duration or count), an end of 
notifications message will be provided to the application. 

Service policies may govern what count values can be requested, including maximum number of notifications allowed 
and whether unlimited notifications can be requested (i.e. either by not specifying the optional Count message part or by 
specifying it with a value of zero). If the count value requested is not in policy, a PolicyException (POL0004 or 
POL0005 as appropriate) will be returned. 

The criteria will be met when the terminal enters the area defined as the circle of the radius provided around the point 
provided (latitude, longitude). The tracking accuracy provided will determine how fine grained the determination of 
where the terminal is at is. A tracking accuracy with a high value (coarse grained tracking) may result in more or less 
notifications (false notifications or missed notifications) than actual entries and exits from the area defined. 

Service policies govern what values can be provided for tracking accuracy, including a minimum number of meters for 
tracking accuracy that can be requested. If the value provided is not within policy, a PolicyException (POL0230) will 
be returned. 
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8.2.1.1 



Input message: StartGeographicalNotificationRequest 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting location event 
notification. The application invokes this operation on 
behalf of this entity. However, it should NOT be assumed 
that the application has authenticated the requester. If this 
part is not present, the requesting entity is the application 
itself. 


Addresses 


xsd:anyURI 
[1.. unbounded] 


No 


Addresses of terminals to monitor 


Latitude 


xsd:float 


No 


Latitude of center point 


Longitude 


xsd:float 


No 


Longitude of center point 


Radius 


xsd:float 


No 


Radius of circle around center point in meters 


Tracking Accuracy 


xsd:float 


No 


Number of meters of acceptable error in tracking distance 


Criteria 


EnteringLeavingCriteria 


No 


Indicates whether the notification should occur when the 
terminal enters or leaves the target area 


Checklmmediate 


xsd:boolean 


No 


Check location immediately after establishing notification 


Frequency 


commonTimelVletric 


No 


Maximum frequency of notifications (can also be 
considered minimum time between notifications) 


Duration 


commonTimelVletric 


Yes 


Period of time notifications are provided for. If set to '0' 
(zero), a default duration time, which is specified by the 
service policy, will be used. If the parameter is omitted, the 
notifications will continue until the maximum duration time, 
which is specified by the service policy, unless the 
notifications are stopped by endNotificationRequest. 


Count 


xsd:int 


Yes 


Maximum number of notifications. For no maximum, either 
do not specify this part or specify a value of zero. 



8.2.1.2 



Output message: StartGeographicalNotificationResponse 



Part name 


Part type 


Optional 


Description 


None 









8.2.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid addresses. 

• SVC0005: Duplicate correlator. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0002: Privacy error. 

• POL0003: Too many addresses. 

• POL0004: Unlimited notifications not supported. 

• POL0005: Too many notifications requested. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

• POL0009: Invalid frequency requested. 

• POL0013: Addresses duplication 
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• POL0230: Requested accuracy not available. 

• POL023 1 : Geographic notification not available. 

8.2.2 Operation: StartPeriodicNotification 

Periodic notifications provide location information for a set of terminals at an application defined interval. The accuracy 
requested is the desired accuracy for the response. If the accuracy requested is not supported, a PolicyException 
(POL0230) will be returned to the application. 



8.2.2.1 



Input message: StartPeriodicNotificationRequest 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting location event 
notification. The application invokes this operation on 
behalf of this entity. However, it should NOT be 
assumed that the application has authenticated the 
requester. If this part is not present, the requesting 
entity is the application itself. 


Addresses 


xsd:anyURI 
[1.. unbounded] 


No 


Addresses of terminals to monitor 


RequestedAccuracy 


xsd:int 


No 


Accuracy of location requested in meters 


Frequency 


common:TimeMetric 


No 


Maximum frequency of notifications (can also be 
considered minimum time between notifications) 


Duration 


common:TimeMetric 


Yes 


Length of time notifications occur for, do not specify to 
use default notification time defined by service policy 



8.2.2.2 



Output message: StartPeriodicNotification Response 



Part name 


Part type 


Optional 


Description 


None 









8.2.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid addresses. 

• SVC0005: Duplicate correlator. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

• POL0002: Privacy error. 

• POL0003: Too many addresses. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 

• POL0009: Invalid frequency requested. 

• POL0013: Addresses duplication 
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• POL0230: Requested accuracy not available. 

• POL0232: Periodic notification not available. 

8.2.3 Operation: EndNotification 

The application may end a notification (either type) using this operation. 

Until this operation returns, notifications may continue to be received by the application. 

An end of notification (endNotification) message will not be delivered to the application for a notification ended using 
this operation. 

8.2.3.1 Input message: EndNotificationRequest 



Part name 


Part type 


Optional 


Description ^^^ 


Correlator 


xsd:string 


No 


Correlator of request to end 



8.2.3.2 Output message: EndNotificationResponse 



Part name 


Part type 


Optional 


Description 


None 









8.2.3.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOOl: Policy error. 

8.2.4 Operation: StartDistanceNotification 

Notifications of distance changes between monitored devices are made available to applications. The number and 
duration of notifications can requested as a part of a setup of the notification or maybe governed by service policies, or 
a combination of the two. 

The correlator provided in the reference must be unique for this Web Service at the time the notification is initiated, 
otherwise a ServiceException (SVC0005) will be returned to the application. 

When specified, the ReferenceAddresses indicates device(s) that will be used as reference device(s) from which the 
distance towards each of monitored devices specified in MonitoredAddresses will be considered when evaluating 
criteria for triggering notifications. 

When multiple devices are indicated in the ReferenceAddresses, then the following applies: 

• Monitored device is considered to be "within a distance", when it is "within a distance" with at least one of 
the reference devices 

• Monitored device is considered to be "beyond a distance", when it is "beyond a distance" from all specified 
reference devices. 

If the same device is indicated in the ReferenceAddresses and the MonitoredAddresses then the distance between 
"them" (that is zero) is not counted for a criteria evaluation. 

If the ReferenceAddresses is not specified, then the distance between each of monitored devices will be considered 
when evaluating criteria to trigger notifications. 
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The maximum number of device addresses that can be specified for ReferenceAddresses and MonitoredAddresses is 
governed by the service poHcy. If the values provided there are not within the poHcy, a PoHcyException (POL0003) 
will be returned. 

If the Checklmmediate is set to true, then notifications will be set up. The current value of the terminal device locations 
will be checked to determine the distances, and the application will be notified in the following situations: 

• if all monitored devices are within the distance provided and the criteria is AllWithinDistance 

• if any of monitored devices is within the distance provided and the criteria is Any WithinDi stance 

• if all monitored devices are beyond the specified distance and the criteria is AllBeyondDi stance 

• if any of monitored devices is beyond the specified distance and the criteria is AnyBeyondDistance 

If the frequency requested is more often than allowed by the service policy, then the value in the service policy will be 
used. If the duration requested exceeds the time allowed in the service policy, then the value in the service policy will 
be used. If the notification period (duration) ends before all of the notifications (count) have been delivered, then the 
notification terminates. When the notifications have run their course (by duration or count), an end of notifications 
message will be provided to the application. 

Service policies may govern what count values can be requested, including maximum number of notifications allowed 
and whether unlimited notifications can be requested (i.e. either by not specifying the optional Count message part or by 
specifying it with a value of zero). If the count value requested is not in policy, a PoHcyException (POL0004 or 
POL0005 as appropriate) will be returned. 

The tracking accuracy provided will determine how fine grained the determination of where the terminal is at is. A 
tracking accuracy with a high value (coarse grained tracking) may result in more or less notifications (false notifications 
or missed notifications) than actual entries and exits from the area defined. 

Service policies govern what values can be provided for tracking accuracy, including a minimum number of meters for 
tracking accuracy that can be requested. If the value provided is not within policy, a PoHcyException (POL0230) will 
be returned. 
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8.2.4.1 



Input message: StartDistanceNotificationRequest 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Requester 


xsd:anyURI 


Yes 


It identifies the entity that is requesting distance event 
notification. The application invokes this operation on 
behalf of this entity. However, it should NOT be 
assumed that the application has authenticated the 
requester. If this part is not present, the requesting 
entity is the application itself. 


ReferenceAddresses 


xsd:anyURI 
[0... unbounded] 


Yes 


If specified, indicates address of each device that will 
be used as reference devices from which the distances 
towards monitored devices indicated in the Addresses 
will be monitored. 


MonitoredAddresses 


xsd:anyURI 
[1... unbounded] 


No 


Contains addresses of devices to monitor. If the 
ReferenceAddress is specified, then the distance 
between each monitored device and reference 
device(s) will be monitored. 
If the ReferenceAddress is not present, then the 
distance between each of the monitored devices will be 
monitored. Note that in that case there must be at least 
two addresses specified here. 


Distance 


xsd:float 


No 


Distance between devices that shall be monitored 


Tracking Accuracy 


xsd:float 


No 


Number of meters of acceptable error in tracking 
distance. 


Criteria 


DistanceCriteria 


No 


Indicates when the notification should occur. 


Checklmmediate 


xsd:boolean 


No 


Check location immediately after establishing 
notification 


Frequency 


commonTimelVletric 


No 


Maximum frequency of notifications (can also be 
considered minimum time between notifications) 


Duration 


commonTimelVletric 


Yes 


Period of time notifications are provided for. If set to '0' 
(zero), a default duration time, which is specified by the 
service policy, will be used. If the parameter is omitted, 
the notifications will continue until the maximum 
duration time, which is specified by the service policy, 
unless the notifications are stopped by 
endNotificationRequest. 


Count 


xsd:int 


Yes 


Maximum number of notifications. For unlimited 
number of notifications, either do not specify this part or 
specify a value of zero. 



8.2.4.2 



Output message: StartDistanceNotification Response 



Part name 


Part type 


Optional 


Description 


None 









8.2.4.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VCOOO 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid addresses. 

• SVC0005: Duplicate correlator. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POLOOO 1 : Policy error. 
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POL0002: Privacy error. 

POL0003: Too many addresses. 

P0LQQQ4: Unlimited notifications not available. 

P0LQQQ5: Too many notifications requested. 

POL0006: Groups not allowed. 

POL0007: Nested groups not allowed. 

POL0009: Invalid frequency requested. 

POL0013: Addresses duplication 

POL0230: Requested accuracy not available. 

POL0233: Distance notification not available. 
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8.3 



Interface: TerminalLocationNotification 



Notification interface to which notifications are deHvered. 

8.3.1 Operation: LocationNotification 

When the location of a monitored device changes a notification is deHvered to the appHcation with the new location 
information. If a group identifier was used, the terminal device URI is provided, not the group URL 



8.3.1.1 



Input message: LocationNotificationRequest 



Part ■ 
name 


^H Part type ^^H 


Optional 


^^^^^^^^^B ^^^^^^^^^^^H 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification 


Data 


Location Data 
[1.. unbounded] 


No 


Location information for terminal 


Criteria 


EnteringLeavingCriteria 


Yes 


Indicates whether the notification was caused by the terminal 
entering or leaving the target area. (This part is provided for 
geographical notifications, not for periodic notifications) 



8.3.1.2 



Output message: LocationNotificationResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.1.3 

None. 



Referenced faults 



8.3.2 Operation: LocationError 

The location error message is sent to the appHcation to indicate that the notification for a terminal, or for the whole 
notification, is being cancelled by the Web Service. 



8.3.2.1 



Input message: LocationErrorRequest 



^ Part 
name 


Part type 


Optional 


Description ^^^^^^^P 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification. 


Address 


xsd:anyURI 


Yes 


Address of terminal if the error applies to an individual terminal, or not 
specified if it applies to the whole notification. 


Reason 


common:ServiceError 


No 


Reason notification is being discontinued. 



8.3.2.2 



Output message: LocationErrorResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.2.3 

None. 



Referenced faults 
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8.3.3 Operation: LocationEnd 

The notifications have completed for this correlator. This message will be delivered when the duration or count for 
notifications have been completed. This message will not be delivered in the case of an error ending the notifications or 
deliberate ending of the notifications (using endNotification operation). 



8.3.3.1 



8.3.3.2 



Input message: LocationEndRequest 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification. 



Output message: LocationEndResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.3.3 

None. 



Referenced faults 



8.3.4 Operation: DistanceNotification 



When monitored terminal devices (all or any of them, depending on the selected criteria) get(s) within a specified 
distance to the reference terminal device (or to each other, in case no reference device address is specified) or when the 
monitored devices (all or any of them, depending on the selected criteria) get(s) beyond the specified distance from the 
reference terminal device(s) (or beyond each other, in case no reference address is specified), a notification is delivered 
to the application. 



8.3.4.1 



8.3.4.2 



Input message: DistanceNotificationRequest 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator provided in request to set up this notification 


Data 


Location Data 
[1.. unbounded] 


No 


Location information for terminals 


Criteria 


DistanceCriteria 


No 


Indicates criteria that triggered the notification 



Output message: DistanceNotificationResponse 



Part name 


Part type 


Optional 


Description 


None 









8.3.4.3 

None. 



Referenced faults 
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Fault definitions 



New fault definitions for this service. 



9.1 

9.1.1 



9.2 
9.2.1 



Fault: ServiceException 
SVC0200: Accuracy out of limit. 



Name 


Description 


Message Id 


SVC0200 


Text 


Accuracy of location is not within acceptable limit. 


Variables 


None 



Fault: PolicyException 

POL0230: Requested accuracy not supported. 



Name 


Description j 


Message Id 


POL0230 


Text 


Requested accuracy is not supported. 


Variables 


None 



9.2.2 POL0231 : Geographic notification not available 



Name 


Description 


Message Id 


POL0231 


Text 


Geographic notification is not available 


Variables 


None 



9.2.3 POL0232: Periodic notification not available 



P Name 


Description 


Message Id 


POL0232 


Text 


Periodic notification is not available 


Variables 


None 



9.2.4 POL0233: Distance notification not available 



^ Name 


Description 


Message Id 


POL0233 


Text 


Distance notification not available 


Variables 


None 
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10 Service policies 


riame 


lype 


uescription 


Minimum Accuracy 


xsd:int 


IVIinimum value for requested accuracy 


IVIinimumAcceptableAccuracy 


xsd:int 


Minimum value for acceptable accuracy 


IVIinimumTrackingAccuracy 


xsd:int 


Minimum value for tracking accuracy 


GeograpliicalNotificationAvailable 


xsd:boolean 


Can notifications be set on a geography 


PeriodicNotificationAvailable 


xsd:boolean 


Can a periodic notification be set up 


AltitudeAlwaysAvailable 


xsd:boolean 


Is altitude available for all location responses 


AltitudeSometimesAvailable 


xsd:boolean 


Is altitude available for some or all location responses (if 
AltitudeAlwaysAvailable is true, this is also true) 


IVIaximumNotificationAddresses 


xsd:int 


Maximum number of addresses for which a notification can 
be set up 


IVIaxNumReferenceAddresses 


xsd:int 


Maximum number of reference device addresses that can be 
specified for distance related notifications 


MaxNumlVlonitoredAddresses 


xsd:int 


Maximum number of monitored device addresses that can be 
specified for distance related notifications 


IVIaximumNotificationFrequency 


commonTimelVletric 


Maximum rate of notification delivery (also can be considered 
minimum time between notifications) 


DefaultNotificationDuration 


commonTimelVletric 


Default amount of time a notification will be set up for 


IVIaximumNotificationDuration 


commonTimelVletric 


Maximum amount of time a notification may be set up for 


IVIaximumCount 


xsd:int 


Maximum number of notifications that may be requested 


UnlimitedCountAllowed 


xsd:boolean 


Allowed to specify unlimited notification count (i.e. either by 
not specifying the optional Count message part in 
StartGeographicalNotificationRequest or by specifying a 
value of zero) 


GroupSupport 


xsd:boolean 


Groups URIs may be used 


NestedGroupSupport 


xsd:boolean 


Are nested groups supported in group definitions 


AddressesDuplicationNotAllowed 


xsd:boolean 


Is duplication addresses supported for location operations 



NOTE: For service policy - "AddressesDuplicationNotAllowed" , If alias/group is used, 

1 . Parlay X GW with Identity Management Framework support can verify that indeed there is a 
duplicate. 

2. If network capability supports alias/group and the Parlay-X GW without Identity Management 
Framework supporting, then the policy exception of addresses duplication may not have effect fully. 

3. If network capability don't support alias/group and the Parlay-X GW without Identity Management 
Framework supporting, the Parlay-X GW should reject the alias/group. 
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Annex A (normative): 
WSDL for terminal location 



The document/literal WSDL representation of this interface specification is compHant to 3GPP TS 29.199-1 [6] and is 
contained in text files; 

• parlayx_terminal_location_interface_4_0.wsdl 

• parlayx_terminal_location_notification_interf ace_4_0 . wsdl 

• parlayx_terniinal_location_notification_manager_interface_4_0.wsdl 

• parlayx_terminal_location_notification_manager_service_4_0.wsdl 

• parlayx_terminal_location_notification_service_4_0.wsdl 

• parlayx_terminal_location_service_4_0. wsdl 

• parlayx_terminal_location_types_4_0.xsd 
which accompany the present document. 

The WSDL files have been verified using the following files: 

• 9_wsdl2Java_axis-l_4.bat 

• 9_wsdl2Java_axis2-l_4_l.bat 
which accompany the present document. 
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Annex B (informative): 

Description of Parlay X Web Services Part 9: Terminal 

location for 3GPP2 cdma2000 networks 

This annex is intended to define the OSA Parlay X Web Services Stage 3 interface definitions and it provides the 
complete OSA specifications. It is an extension of OSA Parlay X Web Services specifications capabilities to enable 
operation in cdma2000 systems environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 
architecture defined in: 

[1] 3GPP2 X.SOOl 1-D: 'cdma2000 Wireless IP Network Standard ", Version 1.1 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 3.0 

[3] 3GPP2 X.S0013-A: "All-IP Core Network Multimedia Domain" 

These requirements are expressed as additions to and/or exclusions from the 3GPP specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3 GPP 

OSA specifications. 



B.1 General Exceptions 



The terms 3GPP and UMTS are not applicable for the cdma2000 family of standards. Nevertheless these terms are used 
(3GPP TR 21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions 
or exclusions required. 

CAMEL mappings are not applicable for cdma2000 systems. 



B.2 Specific Exceptions 
B.2.1 Clause 1: Scope 

There are no additions or exclusions. 

B.2.2 Clause 2: References 

There are no additions or exclusions. 

B.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

B.2. 4 Clause 4: Detailed service description 

There are no additions or exclusions. 

B.2. 5 Clause 5: Namespaces 

There are no additions or exclusions. 
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B.2.6 Clause 6: Sequence diagrams 

There are no additions or exclusions. 

B.2.7 Clause 7: XML Schema data type definition 

There are no additions or exclusions. 

B.2.8 Clause 8: Web Service interface definition 

There are no additions or exclusions. 

B.2.9 Clause 9: Fault definitions 

There are no additions or exclusions. 

B.2.10 Clause 10: Service policies 

There are no additions or exclusions. 

B.2.1 1 Annex A (normative): WSDL for terminal location 

There are no additions or exclusions. 
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Annex C (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Cat 


Old 


New 


Jun 2006 


CT 32 


CP-06021 1 


0005 


-- 


Parameterization for requester of Terminal Location Web service 


B 


6.3.0 


7.0.0 


Dec 2006 


CT 34 


CP-060604 


0007 


-- 


Complete the description of the new requester message part 


F 


7.0.0 


7.1.0 


Mar 2007 


CT 35 


CP-070048 


0010 


-- 


Applying SVC0004 for a single address in Terminal Location Web Service 


C 


7.1.0 


7.2.0 


Mar 2007 


CT 35 


CP-070045 


0009 


-- 


Add OSA Parlay Web Services support for 3GPP2 networks 


A 


7.1.0 


7.2.0 


Mar 2007 


-- 


-- 


-- 


-- 


Editorial: Aligned 5 Namespaces 


-- 


7.2.0 


7.2.1 


Jun 2007 


-- 


-- 


-- 


-- 


Renamed in Introduction Part 18:"Device management" to "Device 
Capabilities and Configuration" 


-- 


7.2.1 


7.2.2 


Dec 2008 


CT_42 


CP-080891 


0012 


-- 


Remove ambiguity in description of the 'duration' parameter in the 
Notification Request method in Parlay X Terminal Location 


F 


7.2.2 


8.0.0 


Sep 2009 


CT 45 


CP-090597 


0013 




Completion of Parlay X Terminal location for Release 8 


F 


8.0.0 


8.1.0 


2009-12 


- 


- 


- 


- 


Update to Rel-9 version (MCC) 




8.1.0 


9.0.0 
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